Documentation: adding new components #16845
Conversation
Add component contribution guidelines
davewhitley
added
[Type] Developer Documentation
davewhitley
requested review from
ajitbohra,
chrisvanpatten,
gziolo,
jorgefilipecosta,
talldan and
youknowriad
as code owners
|
|
||
| ## Deprecation | ||
|
|
||
| A component/feature may need deprecation if: |
There was a problem hiding this comment.
We should emphasize that this applies not only to components but also to their props, whenever we add a new one, rename or remove. This should be reflected in the docs but at the same time we should ensure that old code still works as close as possible to what was before and deprecation warnings are outputted to the Web Console encouraging to use the new recommended version.
There was a problem hiding this comment.
I wonder if this section belongs to this document, since this is generic and applies to any public API of the project. (A backward compatibility policy document)
There was a problem hiding this comment.
From my experience, it doesn't harm to repeat it a couple of times in our docs 😃
There was a problem hiding this comment.
I have no idea where our backward compatibility policy document is—linking to it here might be a good approach, but it's definitely helpful being as explicit as possible about our approach here, specifically with reference to how that works for components.
There was a problem hiding this comment.
I agree there are some component specific things that can be included here.
There was a problem hiding this comment.
Overall this looks 💯. Yay for contribution guidelines! I've made some (mostly nitpicky, fairy minor) changes and suggestions.
The three biggest changes I'd suggest are:
- Simplifying language wherever possible to be more concrete and less abstract (including examples helps a lot) and to make it a bit friendlier to contributors whose first language isn't English.
- Lead with documentation (or at least draft documentation) rather than with visual designs, to encourage people to think first about usage patterns, functionality, and semantics.
- Make design, development, and accessibility reviews clear blockers to merging new components.
|
|
||
| ## Deprecation | ||
|
|
||
| A component/feature may need deprecation if: |
There was a problem hiding this comment.
I have no idea where our backward compatibility policy document is—linking to it here might be a good approach, but it's definitely helpful being as explicit as possible about our approach here, specifically with reference to how that works for components.
Small tweaks to improve copy. Co-Authored-By: sarah ✈ semark <[email protected]>
| @@ -0,0 +1,82 @@ | |||
| # Contributing components | |||
There was a problem hiding this comment.
Maybe "Contributing to WordPress Interface Components"?
|
Thanks for the reviews everyone! I've gathered some non-blocking issues that need some next steps:
Can someone more knowledgeable that me please handle the last one in another PR? |
|
@sarahmonster mind giving this another look? I think it's ready to go and other improvements could be made in following PRs. |
* Initial commit Add component contribution guidelines * Apply suggestions from code review Small tweaks to improve copy. Co-Authored-By: sarah ✈ semark <[email protected]> * Copy tweaks * Simplify language
* Initial commit Add component contribution guidelines * Apply suggestions from code review Small tweaks to improve copy. Co-Authored-By: sarah ✈ semark <[email protected]> * Copy tweaks * Simplify language
Description
This is a first attempt at including some sort of guidance for adding/proposing/suggesting new components to the wordpress/components npm package. I pulled documentation from several different sources.
We need guidelines for:
It's not comprehensive, but I expect this document to evolve as we add more components.
cc @sarahmonster @karmatosed